introduce `agave-unstable-api` throughout the monorepo #8424

t-nelson · 2025-10-10T06:33:19Z

Problem

we publish a bunch of crates from the monorepo that we have no desire to adhere to semver or in any way maintain a stable api. people use these crates anyway, then cry when we break them. See #8424

Summary of Changes

make consumers of unstable apis sign a contract

introduce a new crate feature agave-unstable-api
gate the entrypoint (lib.rs) of every crate on it
add it to every crate's default feature, to avoid breaking anyone today

NOTE: this is a ham-fisted first pass. it blankets every crate. even the ones that we do more or less intend to be consumed. i'm indifferent as to whether we want to try to make those determinations here, or wait 'til later. there's no time crunch until we're ready to cut v4.0.0. i'll merge this with rebase+merge strategy to ~~pad my github metrics~~ ease reverting the changes on any crates after the fact

when we branch v4.0, we will remove agave-unstable-api from default features, freeing us of our burden

closes #3724

mergify · 2025-10-10T06:33:53Z

If this PR represents a change to the public RPC API:

Make sure it includes a complementary update to rpc-client/ (example)
Open a follow-up PR to update the JavaScript client @solana/kit (example)

Thank you for keeping the RPC clients in sync with the server API @t-nelson.

mergify · 2025-10-10T06:33:54Z

The Firedancer team maintains a line-for-line reimplementation of the
native programs, and until native programs are moved to BPF, those
implementations must exactly match their Agave counterparts.
If this PR represents a change to a native program implementation (not
tests), please include a reviewer from the Firedancer team. And please
keep refactors to a minimum.

mergify · 2025-10-10T06:33:55Z

For your information, the solana-zk-token-sdk is deprecated, and this
directory will be removed in a future version. Please take this in mind
when making modifications.

steviez

Couple items and a couple nits, I don't feel too strongly about alphabetizing the features in feature lists

turbine/src/lib.rs

bench-vote/Cargo.toml

gossip/src/lib.rs

poh-bench/Cargo.toml

programs/loader-v4/src/lib.rs

rpc-client/Cargo.toml

svm-rent-calculator/src/lib.rs

syscalls/Cargo.toml

tpu-client-next/Cargo.toml

tpu-client/Cargo.toml

cargo-registry/Cargo.toml

codecov-commenter · 2025-10-10T20:32:42Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.2%. Comparing base (5aac226) to head (40a4b0c).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #8424   +/-   ##
=======================================
  Coverage    83.2%    83.2%           
=======================================
  Files         839      839           
  Lines      367877   367875    -2     
=======================================
+ Hits       306122   306158   +36     
+ Misses      61755    61717   -38

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

t-nelson · 2025-10-10T20:37:30Z

Couple items and a couple nits, I don't feel too strongly about alphabetizing the features in feature lists

will address in a couple hours. some of these make me question our ci since, if we actually had coverage, there's no way it would be green right now 🤔

steviez · 2025-10-10T20:53:53Z

Couple items and a couple nits, I don't feel too strongly about alphabetizing the features in feature lists

will address in a couple hours. some of these make me question our ci since, if we actually had coverage, there's no way it would be green right now 🤔

To confirm, you're not talking about alphabetizing right (that is seemingly a setting to be turned on if such a setting exists) ?

As for the other items - Looking at solana-turbine as an example, the callers are enabling the feature. Ie, see solana-core:

agave/core/Cargo.toml

Line 163 in ee1b5d0

solana-turbine = { workspace = true, features = ["agave-unstable-api"] }

I'm guessing having stuff gated twice behind [cfg(feature = "agave-unstable-api")] isn't a compile error so I think we're good. Or, am I missing something else that you're concerned about ?

joncinque

Sorry, I might be missing something really obvious, but isn't this a breaking change for anyone using default-features = false on any crates currently?

Since every crate has #![cfg(feature = "agave-unstable-api")] at the top, it means that downstream users get nothing if agave-unstable-api is disabled.

We probably just want to add the crate feature to every Cargo.toml and that's it, no?

Edit: otherwise, we're just creating completely unnecessary churn for downstream people who will just blindly add agave-unstable-api to all of their agave deps

t-nelson · 2025-10-10T22:46:48Z

Couple items and a couple nits, I don't feel too strongly about alphabetizing the features in feature lists

will address in a couple hours. some of these make me question our ci since, if we actually had coverage, there's no way it would be green right now 🤔

To confirm, you're not talking about alphabetizing right (that is seemingly a setting to be turned on if such a setting exists) ?

actually the svm rent-collector one. ci should have puked but i bet it just has zero coverage

t-nelson · 2025-10-11T23:15:07Z

Sorry, I might be missing something really obvious, but isn't this a breaking change for anyone using default-features = false on any crates currently?

technically yes, but how many of those are there and they are using what we deem to be unstable api. is there a lower touch path here?

Since every crate has #![cfg(feature = "agave-unstable-api")] at the top, it means that downstream users get nothing if agave-unstable-api is disabled.

that is ultimately the desired effect. to anyone who comes to us about broken interfaces in these crates i want to be able to say, "what did you think that agave-unstable-api crate flag meant?"

We probably just want to add the crate feature to every Cargo.toml and that's it, no?

maybe?

Edit: otherwise, we're just creating completely unnecessary churn for downstream people who will just blindly add agave-unstable-api to all of their agave deps

downstream is invalid here. the point of the crate feature is to make them admit they're using unstable crates

alexpyattaev · 2025-10-12T06:25:55Z

It would appear that the following crates might break with default features disabled:

tokens/Cargo.toml
13:default = ["remote-wallet-hidraw"]

tpu-client/Cargo.toml
16:default = ["spinner"]

cargo-registry/Cargo.toml
16:default = ["remote-wallet-hidraw"]

tpu-client-next/Cargo.toml
16:default = ["log"]

stake-accounts/Cargo.toml
16:default = ["remote-wallet-hidraw"]

remote-wallet/Cargo.toml
16:default = ["linux-static-hidraw"]

programs/vote/Cargo.toml
20:default = ["metrics"]

cli/Cargo.toml
20:default = ["remote-wallet-hidraw"]

keygen/Cargo.toml
20:default = ["remote-wallet-hidraw"]

syscalls/Cargo.toml
16:default = ["metrics"]

programs/sbf/rust/panic/Cargo.toml
15:default = ["custom-panic"]

programs/sbf/rust/custom_heap/Cargo.toml
15:default = ["custom-heap"]

programs/bpf_loader/Cargo.toml
20:default = ["metrics"]

For the most part our crates do not have default features enabled=>amount of breakage would be limited. We could of course do what @t-nelson is proposing for those crates that do not have default-features, and what @joncinque for the rest.

t-nelson · 2025-10-13T18:50:20Z

It would appear that the following crates might break with default features disabled:

tokens/Cargo.toml
13:default = ["remote-wallet-hidraw"]

tpu-client/Cargo.toml
16:default = ["spinner"]

cargo-registry/Cargo.toml
16:default = ["remote-wallet-hidraw"]

tpu-client-next/Cargo.toml
16:default = ["log"]

stake-accounts/Cargo.toml
16:default = ["remote-wallet-hidraw"]

remote-wallet/Cargo.toml
16:default = ["linux-static-hidraw"]

programs/vote/Cargo.toml
20:default = ["metrics"]

cli/Cargo.toml
20:default = ["remote-wallet-hidraw"]

keygen/Cargo.toml
20:default = ["remote-wallet-hidraw"]

syscalls/Cargo.toml
16:default = ["metrics"]

programs/sbf/rust/panic/Cargo.toml
15:default = ["custom-panic"]

programs/sbf/rust/custom_heap/Cargo.toml
15:default = ["custom-heap"]

programs/bpf_loader/Cargo.toml
20:default = ["metrics"]

For the most part our crates do not have default features enabled=>amount of breakage would be limited. We could of course do what @t-nelson is proposing for those crates that do not have default-features, and what @joncinque for the rest.

most of these are bin crates. all of the lib crates where there was a problem were caught by ci and corrected already. do you have a specific instances that needs corrected?

t-nelson · 2025-10-13T20:26:10Z

Couple items and a couple nits, I don't feel too strongly about alphabetizing the features in feature lists

everything here is addressed now

alexpyattaev · 2025-10-13T20:32:54Z

most of these are bin crates. all of the lib crates where there was a problem were caught by ci and corrected already. do you have a specific instances that needs corrected?

No I think we're good, just copied the data here for the record.

alexpyattaev · 2025-10-13T20:36:05Z

gossip/src/lib.rs

@gregcusack do we want to blanket agave-unstable-api over gossip? I think it might be a bit overkill in this case as it is likely to be used externally.

isn't the agave-unstable-api on by default? so end users shouldn't be affected? They can still use the gossip crate

Yes, true, the point is we have hidden a bunch of unstable multihoming logic behind this flag, enabling it by default would allow external users to depend on that API

alexpyattaev · 2025-10-13T20:40:11Z

turbine/Cargo.toml

 edition = { workspace = true }

 [features]
+default = ["agave-unstable-api"]


We explicitly did not want to have turbine exposed at all as we intend to have breaking changes there. adding this to default features would undo that.

the whole point of this change set is to give us free reign to break these interfaces. if something is gated by this crate feature, we tell anyone complaining about breakage to fuck off

Yes but right now turbine already has it disabled by default, and entirety of its API is invisible already since 3.0. No point exposing it again.

alexpyattaev · 2025-10-13T20:43:05Z

I believe this PR may expose a bunch of things we have already hidden behind agave-unstable-api by making it a default feature, which is not ideal. Not sure if there is a good workaround for that.

gregcusack · 2025-10-14T16:37:46Z

I believe this PR may expose a bunch of things we have already hidden behind agave-unstable-api by making it a default feature, which is not ideal. Not sure if there is a good workaround for that.

oh yesssss i see what you are saying. true. if our original intent was "if you want to use multihoming, know it's all unstable". and now our intent is "if you want to use gossip, know it is all unstable". then i think we're generally fine since the multihoming stuff is kinda a subset of gossip stuff.

…` crate

…-tracker` crate

… crate

…client-types` crate

…ogic` crate

…ool` crate

…iver` crate

… crate

…ram` crate

…m` interface

…ogram` crate

…ram` crate

…interface

t-nelson · 2025-10-15T03:52:25Z

ok this is updated as per comments on the issue. we have relaxed the initial behavior to throw a deprecation warning if the agave-unstable-api crate feature is not specified rather rug the symbols outright and specify the feature in default-features

any crates that had partially employed agave-unstable-api already now apply it to the entire crate interface

bin crates have now been dropped where convenient

there are at least two outstanding issues, which are that genesis and vortexor dirs specify two targets, one bin and one lib. initial search didn't reveal an obvious way to remove the default feature specification

t-nelson requested review from a team, joncinque and steviez October 10, 2025 06:33

t-nelson requested review from a team as code owners October 10, 2025 06:33

t-nelson changed the title ~~introduce agave-unstable-api throughout the monorep~~ introduce agave-unstable-api throughout the monorepo Oct 10, 2025

t-nelson force-pushed the aua branch 2 times, most recently from 66b599a to 3ced707 Compare October 10, 2025 19:47

steviez reviewed Oct 10, 2025

View reviewed changes

cargo-registry/Cargo.toml Outdated Show resolved Hide resolved

joncinque reviewed Oct 10, 2025

View reviewed changes

t-nelson force-pushed the aua branch from 3ced707 to 40a4b0c Compare October 13, 2025 17:52

alexpyattaev reviewed Oct 13, 2025

View reviewed changes

t-nelson added 28 commits October 14, 2025 21:33

introduce agave-unstable-api feature to `solana-transaction-context…

30e8ea5

…` crate

introduce agave-unstable-api feature to `solana-transaction-metrics…

5690a8a

…-tracker` crate

introduce agave-unstable-api feature to solana-transaction-status…

4150308

… crate

introduce agave-unstable-api feature to `solana-transaction-status-…

643ec05

…client-types` crate

introduce agave-unstable-api feature to agave-transaction-view crate

e7bda76

apply agave-unstable-api feature to entire solana-turbine interface

028a59e

introduce agave-unstable-api feature to solana-udp-client crate

6fd9d75

introduce agave-unstable-api feature to `solana-unified-scheduler-l…

4d7ed48

…ogic` crate

introduce agave-unstable-api feature to `solana-unified-scheduler-p…

cc22ac5

…ool` crate

introduce agave-unstable-api feature to `agave-verified-packet-rece…

4080f30

…iver` crate

introduce agave-unstable-api feature to solana-version crate

ed4afaf

introduce agave-unstable-api feature to solana-vortexor crate

11740f5

introduce agave-unstable-api feature to solana-vote crate

903fe2d

introduce agave-unstable-api feature to solana-votor-messages crate

8fc3ff8

apply agave-unstable-api feature to entire solana-votor interface

e813c6f

introduce agave-unstable-api feature to solana-wen-restart crate

ed79484

introduce agave-unstable-api feature to agave-xdp crate

3faff4c

introduce agave-unstable-api feature to solana-zk-token-sdk crate

691dc90

introduce agave-unstable-api feature to solana-curve25519 crate

45df78d

introduce agave-unstable-api feature to solana-bpf-loader-program…

6e7395d

… crate

introduce agave-unstable-api feature to `solana-compute-budget-prog…

7402e03

…ram` crate

apply agave-unstable-api feature to entire `solana-loader-v4-progra…

8d2b6f3

…m` interface

introduce agave-unstable-api feature to solana-stake-program crate

6018739

introduce agave-unstable-api feature to solana-system-program crate

24a8baf

introduce agave-unstable-api feature to solana-vote-program crate

0a84e02

introduce agave-unstable-api feature to `solana-zk-elgamal-proof-pr…

7e5ed89

…ogram` crate

introduce agave-unstable-api feature to `solana-zk-token-proof-prog…

32f0ea8

…ram` crate

apply agave-unstable-api crate feature to entire agave-snapshots …

0abd38e

…interface

t-nelson force-pushed the aua branch from 40a4b0c to 0abd38e Compare October 15, 2025 03:40

introduce agave-unstable-api throughout the monorepo #8424

Are you sure you want to change the base?

introduce agave-unstable-api throughout the monorepo #8424

Conversation

t-nelson commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Summary of Changes

Uh oh!

mergify bot commented Oct 10, 2025

Uh oh!

mergify bot commented Oct 10, 2025

Uh oh!

mergify bot commented Oct 10, 2025

Uh oh!

steviez left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented Oct 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

t-nelson commented Oct 10, 2025

Uh oh!

steviez commented Oct 10, 2025

Uh oh!

joncinque left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

t-nelson commented Oct 10, 2025

Uh oh!

t-nelson commented Oct 11, 2025

Uh oh!

alexpyattaev commented Oct 12, 2025

Uh oh!

t-nelson commented Oct 13, 2025

Uh oh!

t-nelson commented Oct 13, 2025

Uh oh!

alexpyattaev commented Oct 13, 2025

Uh oh!

alexpyattaev Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

gregcusack Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

alexpyattaev Oct 14, 2025

Choose a reason for hiding this comment

Uh oh!

alexpyattaev Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

t-nelson Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

alexpyattaev Oct 13, 2025

Choose a reason for hiding this comment

Uh oh!

alexpyattaev commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gregcusack commented Oct 14, 2025

Uh oh!

t-nelson commented Oct 15, 2025

Uh oh!

Reviewers

Assignees

introduce `agave-unstable-api` throughout the monorepo #8424

introduce `agave-unstable-api` throughout the monorepo #8424

t-nelson commented Oct 10, 2025 •

edited

Loading

codecov-commenter commented Oct 10, 2025 •

edited

Loading

joncinque left a comment •

edited

Loading

alexpyattaev commented Oct 13, 2025 •

edited

Loading